package com.numberone.iotplatform.service;

import com.numberone.iotplatform.dto.a_i_box.*;
import java.util.List;
import java.util.Optional;

/**
 * AI BOX 设备 API 封装服务接口 (完整版)
 * 严格对应《AI BOX Web API 接口说明 V1.0.20》文档。
 */
public interface AiBoxApiService {

    // =================================================================
    // 1. 登录退出
    // =================================================================

    /**
     * @see <a href="文档章节 1.1">1.1 登录</a>
     */
    boolean login(String ip, int port, String username, String password);

    /**
     * @see <a href="文档章节 1.2">1.2 退出</a>
     */
    boolean logout(String ip, int port);


    // =================================================================
    // 2. 系统配置
    // =================================================================

    // --- 2.1 系统维护 ---
    /** @see <a href="文档章节 2.1.1">2.1.1 重启设备</a> */
    boolean rebootDevice(String ip, int port);
    /** @see <a href="文档章节 2.1.4">2.1.4 固件升级</a> */
    boolean upgradeFirmware(String ip, int port, FirmwareUpgradeDTO firmware);

    // --- 2.2 系统设置 ---
    /** @see <a href="文档章节 2.2.1">2.2.1 获取网络参数</a> */
    Optional<NetworkInfoDTO> getNetworkInfo(String ip, int port);
    /** @see <a href="文档章节 2.2.2">2.2.2 设置网络参数</a> */
    boolean setNetworkInfo(String ip, int port, NetworkInfoDTO networkInfo);
    /** @see <a href="文档章节 2.2.3">2.2.3 获取系统时间及ntp服务器</a> */
    Optional<TimeInfoDTO> getTimeInfo(String ip, int port);
    /** @see <a href="文档章节 2.2.4">2.2.4 设置系统时间及ntp服务器</a> */
    boolean setTimeInfo(String ip, int port, TimeInfoDTO timeInfo);
    /** @see <a href="文档章节 2.2.5">2.2.5 webserver HTTP/HTTPS模式切换</a> */
    boolean setWebServerMode(String ip, int port, WebServerModeDTO mode);
    /** @see <a href="文档章节 2.2.6">2.2.6 获取设备信息</a> */
    Optional<DeviceInfoDTO> getDeviceInfo(String ip, int port);

    // --- 2.3 通道管理 ---
    /** @see <a href="文档章节 2.3.1">2.3.1 通道管理——手动添加</a> */
    Optional<AddChannelResponseDTO> addChannelManually(String ip, int port, ChannelDTO channelConfig);
    /** @see <a href="文档章节 2.3.2">2.3.2 通道管理——onvif搜索</a> */
    Optional<OnvifDiscoveryResultDTO> discoverOnvifDevices(String ip, int port);
    /** @see <a href="文档章节 2.3.3">2.3.3 通道管理——自动添加</a> */
    Optional<AddChannelResponseDTO> addChannelAutomatically(String ip, int port, OnvifChannelDTO channelConfig);
    /** @see <a href="文档章节 2.3.4">2.3.4 通道删除</a> */
    boolean deleteChannel(String ip, int port, int channelId);
    /** @see <a href="文档章节 2.3.5">2.3.5 通道修改</a> */
    boolean updateChannel(String ip, int port, ChannelUpdateDTO channelUpdate);
    /** @see <a href="文档章节 2.3.6">2.3.6 通道获取</a> */
    Optional<List<ChannelInfoDTO>> getChannels(String ip, int port);
    /** @see <a href="文档章节 2.3.7">2.3.7 获取通道截图</a> */
    Optional<String> getChannelSnapshot(String ip, int port, int videoNo); // 返回 base64 字符串
    /** @see <a href="文档章节 2.3.8">2.3.8 通道模式切换</a> */
    boolean setChannelMode(String ip, int port, ChannelModeDTO channelMode);

    // =================================================================
    // 3. 数据对接
    // =================================================================

    // --- 3.1 FTP推图 ---
    /** @see <a href="文档章节 3.1.1">3.1.1 FTP推图参数设置 PUT</a> */
    boolean setFtpUploadConfig(String ip, int port, FtpConfigDTO ftpConfig);
    /** @see <a href="文档章节 3.1.2">3.1.2 FTP 推图参数获取 GET</a> */
    Optional<FtpConfigDTO> getFtpUploadConfig(String ip, int port);
    /** @see <a href="文档章节 3.1.3">3.1.3 FTP 推图连接测试 POST</a> */
    boolean testFtpConnection(String ip, int port, FtpTestDTO ftpTest);

    // --- 3.2 主动上报 ---
    /** @see <a href="文档章节 3.2.1.1">3.2.1.1 ws 主动上报设置</a> */
    boolean setWsReportsConfig(String ip, int port, WsReportConfigDTO wsConfig);
    /** @see <a href="文档章节 3.2.1.2">3.2.1.2 ws 主动上报参数查询</a> */
    Optional<WsReportConfigDTO> getWsReportsConfig(String ip, int port);
    /** @see <a href="文档章节 3.2.2.1">3.2.2.1 设置 HTTP 主动上报</a> */
    boolean setHttpReportsConfig(String ip, int port, HttpReportConfigDTO httpConfig);
    /** @see <a href="文档章节 3.2.2.2">3.2.2.2 查询 HTTP 主动上报</a> */
    Optional<HttpReportConfigDTO> getHttpReportsConfig(String ip, int port);

    // =================================================================
    // 4. Faces 人脸入库 API
    // =================================================================

    /** @see <a href="文档章节 4.1">4.1 人脸注册/入库</a> */
    Optional<FaceAddResponseDTO> addFace(String ip, int port, FaceAddRequestDTO faceData);
    /** @see <a href="文档章节 4.2">4.2 查询人脸库所有人脸列表</a> */
    Optional<FaceListResponseDTO> listAllFaces(String ip, int port, int pageOffset, int pageSize);
    /** @see <a href="文档章节 4.3">4.3 删除某个人脸</a> */
    boolean deleteFace(String ip, int port, String faceToken);
    /** @see <a href="文档章节 4.4">4.4 删除某个原始图片</a> */
    boolean deleteFaceImage(String ip, int port, String imageId);
    /** @see <a href="文档章节 4.5">4.5 获取某人脸信息与扣图</a> */
    Optional<FaceDetailDTO> getFaceDetail(String ip, int port, String faceToken);
    /** @see <a href="文档章节 4.6">4.6 获取某原始照片信息</a> */
    Optional<OriginalImageDTO> getOriginalImage(String ip, int port, String imageId);
    /** @see <a href="文档章节 4.7">4.7 初始化人脸库</a> */
    boolean initializeFaceLibrary(String ip, int port);

    // =================================================================
    // 5. FaceGroups 人脸分组操作
    // =================================================================

    /** @see <a href="文档章节 5.1">5.1 获取人脸组列表</a> */
    Optional<List<FaceGroupDTO>> listFaceGroups(String ip, int port);
    /** @see <a href="文档章节 5.2">5.2 创建人脸分组</a> */
    boolean createFaceGroup(String ip, int port, FaceGroupDTO groupData);
    /** @see <a href="文档章节 5.3">5.3 删除某人脸分组</a> */
    boolean deleteFaceGroup(String ip, int port, String groupId, int deleteAllFace);
    /** @see <a href="文档章节 5.4">5.4 查询某分组绑定列表</a> */
    Optional<FaceListInGroupDTO> listFacesInGroup(String ip, int port, String groupId, int pageOffset, int pageSize);
    /** @see <a href="文档章节 5.5">5.5 绑定人脸到分组</a> */
    Optional<BindingResponseDTO> bindFaceToGroups(String ip, int port, String faceToken, List<String> groupIds);
    /** @see <a href="文档章节 5.6">5.6 解绑人脸与分组关系</a> */
    Optional<BindingResponseDTO> unbindFaceFromGroups(String ip, int port, String faceToken, List<String> groupIds);
    /** @see <a href="文档章节 5.7">5.7 修改人脸分组</a> */
    boolean updateFaceGroup(String ip, int port, FaceGroupUpdateDTO groupData);

    // =================================================================
    // 6. 人脸对比 API
    // =================================================================

    /** @see <a href="文档章节 6.1">6.1 1:1 两张人脸相似度对比</a> */
    Optional<FaceCompareResponseDTO> compareFaces1v1(String ip, int port, FaceCompareRequestDTO compareData);
    /** @see <a href="文档章节 6.2">6.2 1:N 一张图与人脸库搜索</a> */
    Optional<FaceSearchResponseDTO> searchFace1vN(String ip, int port, FaceSearchRequestDTO searchData);

    // =================================================================
    // 7. 人脸视频通道配置 & 8. 警戒规则 & 9 & 10. 轮询
    // =================================================================
    /** @see <a href="文档章节 7.1">7.1 绑定视频通道到分组</a> */
    Optional<BindingResponseDTO> bindVideoToGroups(String ip, int port, int videoNo, List<String> groupIds);
    /** @see <a href="文档章节 8.1">8.1 警戒规则配置</a> */
    boolean setAlertRules(String ip, int port, int videoNo, AlertRuleConfigDTO ruleConfig);
    /** @see <a href="文档章节 9">9. 轮询获取 Capture 抓拍人脸信息</a> */
    Optional<CaptureDTO> pollCapture(String ip, int port);
    /** @see <a href="文档章节 10">10. 轮询获取 Alerts 告警信息</a> */
    Optional<AlertDTO> pollAlerts(String ip, int port);

    // =================================================================
    // 12. 抓拍查询 & 13. ROI 区域资源 & 14. detectLine 资源 & 15. 获取特征
    // =================================================================
    /** @see <a href="文档章节 12">12. 抓拍查询</a> */
    Optional<CaptureQueryResultDTO> queryCaptures(String ip, int port, CaptureQueryDTO query);
    /** @see <a href="文档章节 13.1">13.1 获取 ROI 区域</a> */
    Optional<RoiAreaDTO> getRoiArea(String ip, int port, int videoNo);
    /** @see <a href="文档章节 13.2">13.2 设置 ROI 区域</a> */
    boolean setRoiArea(String ip, int port, int videoNo, RoiAreaDTO roiArea);
    /** @see <a href="文档章节 14.1">14.1 获取 detectLine</a> */
    Optional<DetectLineDTO> getDetectLine(String ip, int port, int videoNo);
    /** @see <a href="文档章节 14.2">14.2 设置 detectLine</a> */
    boolean setDetectLine(String ip, int port, int videoNo, DetectLineDTO detectLine);
    /** @see <a href="文档章节 15">15. 获取人脸图片特征数据</a> */
    Optional<FaceFeatureResponseDTO> getFaceFeature(String ip, int port, FaceFeatureRequestDTO featureRequest);
}